CCI API Reference¶

cci_bind_param¶

int cci_bind_param(int req_handle, int index, T_CCI_A_TYPE a_type, void *value, T_CCI_U_TYPE u_type, char flag)¶

The cci_bind_param function binds data in the bind variable of prepared statement. This function converts value of the given a_type to an actual binding type and stores it. Subsequently, whenever cci_execute() is called, the stored data is sent to the server. If cci_bind_param () is called multiple times for the same index, the latest configured value is valid.

Parameters:	req_handle -- (IN) Request handle of a prepared statement index -- (IN) Location of binding; it starts with 1. a_type -- (IN) Data type of value value -- (IN) Data value to bind u_type -- (IN) Data type to be applied to the database flag -- (IN) bind_flag(CCI_BIND_PTR).
Returns:	Error code (0: success) CCI_ER_BIND_INDEX CCI_ER_CON_HANDLE CCI_ER_NO_MORE_MEMORY CCI_ER_REQ_HANDLE CCI_ER_TYPE_CONVERSION CCI_ER_USED_CONNECTION

To bind NULL to the database, choose one of below settings.

• Set the value of value to a NULL pointer
• Set the value of u_type to CCI_U_TYPE_NULL

The following shows a part of code to bind NULL.

res = cci_bind_param (req, 2 /* binding index*/, CCI_A_TYPE_STR, NULL, CCI_U_TYPE_STRING, CCI_BIND_PTR);

or

res = cci_bind_param (req, 2 /* binding index*/, CCI_A_TYPE_STR, data, CCI_U_TYPE_NULL, CCI_BIND_PTR);

can be used.

If CCI_BIND_PTR is configured for flag, the pointer of value variable is copied (shallow copy), but no value is copied. If it is not configured for flag, the value of value variable is copied (deep copy) by allocating memory. If multiple columns are bound by using the same memory buffer, CCI_BIND_PTR must not be configured for the flag.

T_CCI_A_TYPE is a C language type that is used in CCI applications for data binding, and consists of primitive types such as int and float, and user-defined types defined by CCI such as T_CCI_BIT and T_CCI_DATE. The identifier for each type is defined as shown in the table below.

a_type	value type
CCI_A_TYPE_STR	char *
CCI_A_TYPE_INT	int *
CCI_A_TYPE_FLOAT	float *
CCI_A_TYPE_DOUBLE	double *
CCI_A_TYPE_BIT	T_CCI_BIT *
CCI_A_TYPE_SET	T_CCI_SET
CCI_A_TYPE_DATE	T_CCI_DATE *
CCI_A_TYPE_BIGINT	int64_t * (For Windows: __int64 *)
CCI_A_TYPE_BLOB	T_CCI_BLOB
CCI_A_TYPE_CLOB	T_CCI_CLOB

T_CCI_U_TYPE is a column type of database and data bound though the value argument is converted into this type. The cci_bind_param () function uses two kinds of types to send information which is used to convert U-type data from A-type data; the U-type data can be interpreted by database language and the A-type data can be interpreted by C language.

There are various A-type data that are allowed by U-type data. For example, CCI_U_TYPE_INT can receive CCI_A_TYPE_STR as A-type data including CCI_A_TYPE_INT. For information on type conversion, see Implicit Type Conversion.

Both T_CCI_A_TYPE and T_CCI_U_TYPE enum(s) are defined in the cas_cci.h file. The definition of each identifier is described in the table below.

u_type	Corresponding a_type (default)
CCI_U_TYPE_CHAR	CCI_A_TYPE_STR
CCI_U_TYPE_STRING	CCI_A_TYPE_STR
CCI_U_TYPE_BIT	CCI_A_TYPE_BIT
CCI_U_TYPE_VARBIT	CCI_A_TYPE_BIT
CCI_U_TYPE_NUMERIC	CCI_A_TYPE_STR
CCI_U_TYPE_INT	CCI_A_TYPE_INT
CCI_U_TYPE_SHORT	CCI_A_TYPE_INT
CCI_U_TYPE_FLOAT	CCI_A_TYPE_FLOAT
CCI_U_TYPE_DOUBLE	CCI_A_TYPE_DOUBLE
CCI_U_TYPE_DATE	CCI_A_TYPE_DATE
CCI_U_TYPE_TIME	CCI_A_TYPE_DATE
CCI_U_TYPE_TIMESTAMP	CCI_A_TYPE_DATE
CCI_U_TYPE_OBJECT	CCI_A_TYPE_STR
CCI_U_TYPE_BIGINT	CCI_A_TYPE_BIGINT
CCI_U_TYPE_DATETIME	CCI_A_TYPE_DATE
CCI_U_TYPE_BLOB	CCI_A_TYPE_BLOB
CCI_U_TYPE_CLOB	CCI_A_TYPE_CLOB
CCI_U_TYPE_ENUM	CCI_A_TYPE_STR

When the string including the date is used as an input parameter of DATE, DATETIME, or TIMESTAMP, "YYYY/MM/DD" or "YYYY-MM-DD" is allowed for the date string type. Therefore, "2012/01/31" or "2012-01-31" is valid, but "01/31/2012" is invalid. The following is an example of having the string that includes the date as an input parameter of the date type.

// "CREATE TABLE tbl(aa date, bb datetime)";

char *values[][3] =
{
    {"1994/11/30", "1994/11/30 20:08:08"},
    {"2008-10-31", "2008-10-31 20:08:08"}
};

req = cci_prepare(conn, "insert into tbl (aa, bb) values ( ?, ?)", CCI_PREPARE_INCLUDE_OID, &error);

for(i=0; i< 2; i++)
{
    res = cci_bind_param(req, 1, CCI_A_TYPE_STR, values[i][0], CCI_U_TYPE_DATE, (char)NULL);
    res = cci_bind_param(req, 2, CCI_A_TYPE_STR, values[i][1], CCI_U_TYPE_DATETIME, (char)NULL);
    cci_execute(req, CCI_EXEC_QUERY_ALL, 0, err_buf);
}

cci_bind_param_array¶

int cci_bind_param_array(int req_handle, int index, T_CCI_A_TYPE a_type, void *value, int *null_ind, T_CCI_U_TYPE u_type)¶

The cci_bind_param_array function binds a parameter array for a prepared cci_execute_array() is called, data is sent to the server by the stored value pointer. If cci_bind_param_array () is called multiple times for the same index, the last configured value is valid. If NULL is bound to the data, a non-zero value is configured in null_ind. If value is a NULL pointer, or u_type is CCI_U_TYPE_NULL, all data are bound to NULL and the data buffer used by value cannot be reused. For the data type of value for a_type, see the cci_bind_param() function description.

Parameters:	req_handle -- (IN) Request handle of the prepared statement index -- (IN) Binding location a_type -- (IN) Data type of value value -- (IN) Data value to be bound null_ind -- (IN) NULL indicator array (0 : not NULL, 1 : NULL) u_type -- (IN) Data type to be applied to the database.
Returns:	Error code (0: success) CCI_ER_BIND_INDEX CCI_ER_BIND_ARRAY_SIZE CCI_ER_CON_HANDLE CCI_ER_NO_MORE_MEMORY CCI_ER_REQ_HANDLE CCI_ER_TYPE_CONVERSION CCI_ER_USED_CONNECTION

cci_bind_param_array_size¶

int cci_bind_param_array_size(int req_handle, int array_size)¶

The cci_bind_param_array_size function determines the size of the array to be used in cci_bind_param_array(). cci_bind_param_array_size () must be called first before cci_bind_param_array() is used.

Parameters:	req_handle -- Request handle of a prepared statement array_size -- (IN) binding array size
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_REQ_HANDLE CCI_ER_USED_CONNECTION

cci_bind_param_ex¶

int cci_bind_param_ex(int req_handle, int index, T_CCI_A_TYPE a_type, void *value, int length, T_CCI_U_TYPE u_type, char flag)¶

The cci_bind_param_ex function works as the same with cci_bind_param(). However, it has an additional argument, length, which specifies the byte length of a string if bound data is a string.

Parameters:	req_handle -- (IN) Request handle of the prepared statement index -- (IN) Binding location, starting from 1 a_type -- (IN) Data type of value value -- (IN) Data value to be bound length -- (IN) Byte length of a string to be bound u_type -- (IN) Data type to be applied to the database. flag -- (IN) bind_flag(CCI_BIND_PTR).
Returns:	Error code(0: success)

The length argument can be used for binding a string which includes '\0' as below.

cci_bind_param_ex(statement, 1, CCI_A_TYPE_STR, "aaa\0bbb", 7, CCI_U_TYPE_STRING, 0);

cci_blob_free¶

int cci_blob_free(T_CCI_BLOB blob)¶

The cci_blob_free function frees memory of blob struct.

Returns:	Error code (0: success) CCI_ER_INVALID_LOB_HANDLE

cci_blob_new¶

int cci_blob_new(int conn_handle, T_CCI_BLOB* blob, T_CCI_ERROR* error_buf)¶

The cci_blob_new function creates an empty file where LOB data is stored and returns locator referring to the data to blob struct.

Parameters:	conn_handle -- (IN) Connection handle blob -- (OUT) LOB locator error_buf -- (OUT) Error buffer
Returns:	Error code (0: success) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_USED_CONNECTION

cci_blob_read¶

int cci_blob_read(int conn_handle, T_CCI_BLOB blob, long start_pos, int length, char *buf, T_CCI_ERROR* error_buf)¶

The cci_blob_read function reads as much as data from start_pos to length of the LOB data file specified in blob; then it stores it in buf and returns it.

Parameters:	conn_handle -- (IN) Connection handle blob -- (OUT) LOB locator start_pos -- (IN) Index location of LOB data file length -- (IN) LOB data length from buffer buf -- (IN) Data buffer to read error_buf -- (OUT) Error buffer
Returns:	Size of read value (>= 0: success), Error code (< 0: error) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_INVALID_LOB_READ_POS CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

cci_blob_size¶

long long cci_blob_size(T_CCI_BLOB* blob)¶

The cci_blob_size function returns data file size that is specified in blob.

Parameters:	blob -- (OUT) LOB locator
Returns:	Size of BLOB data file (>= 0: success), Error code (< 0: error) CCI_ER_INVALID_LOB_HANDLE

cci_blob_write¶

int cci_blob_write(int conn_handle, T_CCI_BLOB blob, long start_pos, int length, const char *buf, T_CCI_ERROR* error_buf)¶

The cci_blob_write function reads as much as data from buf to length and stores it from start_pos of the LOB data file specified in blob.

Parameters:	conn_handle -- (IN) Connection handle blob -- (OUT) LOB locator start_pos -- (IN) Index location of LOB data file length -- (IN) Data length from buffer buf -- (OUT) Data buffer to write error_buf -- (OUT) Error buffer
Returns:	Size of written value (>= 0: success), Error code (< 0: error) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

cci_cancel¶

int cci_cancel(int conn_handle)¶

Cancel the running query on the other thread. This function executes the same behavior as Statement.cancel() method in JAVA.

Parameters:	conn_handle -- (IN) Connection handle
Returns:	Error code CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT

The following shows how to cancel the query execution of a thread.

/* gcc -o pthr pthr.c -m64 -I${CUBRID}/include -lnsl ${CUBRID}/lib/libcascci.so -lpthread
*/


#include <stdio.h>
#include <cas_cci.h>
#include <unistd.h>
#include <pthread.h>
#include <string.h>
#include <time.h>

#define QUERY "select * from db_class A, db_class B, db_class C, db_class D, db_class E"

static void *thread_main (void *arg);
static void *execute_statement (int con, char *sql_stmt);

int
main (int argc, char *argv[])
{
    int thr_id = 0, conn_handle = 0, res = 0;
    void *jret;
    pthread_t th;
    char url[1024];
    T_CCI_ERROR error;
    snprintf (url, 1024, "cci:CUBRID:localhost:33000:demodb:PUBLIC::");

    conn_handle = cci_connect_with_url_ex (url, NULL, NULL, &error);

    if (conn_handle < 0)
    {
        printf ("ERROR: %s\n", error.err_msg);
        return -1;
    }

    res = pthread_create (&th, NULL, &thread_main, (void *) &conn_handle);

    if (res < 0)
    {
        printf ("thread fork failed.\n");
        return -1;
    }
    else
    {
        printf ("thread started\n");
    }
    sleep (5);
    // If thread_main is still running, below cancels the query of thread_main.
    res = cci_cancel (conn_handle);
    if (res < 0)
    {
        printf ("cci_cancel failed\n");
        return -1;
    }
    else
    {
        printf ("The query was canceled by cci_cancel.\n");
    }
    res = pthread_join (th, &jret);
    if (res < 0)
    {
        printf ("thread join failed.\n");
        return -1;
    }

    printf ("thread_main was cancelled with\n\t%s\n", (char *) jret);
    free (jret);

    res = cci_disconnect (conn_handle, &error);
    if (res < 0)
    {
        printf ("ERROR: %s\n", error.err_msg);
      return res;
    }

    return 0;
}

void *
thread_main (void *arg)
{
    int con = *((int *) arg);
    int ret_val;
    void *ret_ptr;
    T_CCI_ERROR error;

    cci_set_autocommit (con, CCI_AUTOCOMMIT_TRUE);
    ret_ptr = execute_statement (con, QUERY);
    return ret_ptr;
}

static void *
execute_statement (int con, char *sql_stmt)
{
    int col_count = 1, ind, i, req;
    T_CCI_ERROR error;
    char *buffer;
    char *error_msg;
    int res = 0;

    error_msg = (char *) malloc (128);
    if ((req = cci_prepare (con, sql_stmt, 0, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_prepare ERROR: %s\n", error.err_msg);
        goto conn_err;
    }

    if ((res = cci_execute (req, 0, 0, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_execute ERROR: %s\n", error.err_msg);
        goto execute_error;
    }

    if (res >= 0)
    {
        while (1)
        {
            res = cci_cursor (req, 1, CCI_CURSOR_CURRENT, &error);
            if (res == CCI_ER_NO_MORE_DATA)
            {
                break;
            }
            if (res < 0)
            {
                snprintf (error_msg, 128, "cci_cursor ERROR: %s\n",
                    error.err_msg);
                return error_msg;
            }

            if ((res = cci_fetch (req, &error)) < 0)
            {
                snprintf (error_msg, 128, "cci_fetch ERROR: %s\n",
                    error.err_msg);
                return error_msg;
            }

            for (i = 1; i <= col_count; i++)
            {
                if ((res = cci_get_data (req, i, CCI_A_TYPE_STR, &buffer, &ind)) < 0)
                {
                    snprintf (error_msg, 128, "cci_get_data ERROR\n");
                    return error_msg;
                }
            }
        }
    }

    if ((res = cci_close_query_result (req, &error)) < 0)
    {
        snprintf (error_msg, 128, "cci_close_query_result ERROR: %s\n", error.err_msg);
        return error_msg;
    }
execute_error:
    if ((res = cci_close_req_handle (req)) < 0)
    {
        snprintf (error_msg, 128, "cci_close_req_handle ERROR\n");
    }
conn_err:
    return error_msg;
}

cci_clob_free¶

int cci_clob_free(T_CCI_CLOB clob)¶

The cci_clob_free function frees memory of CLOB struct.

Parameters:	clob -- (IN) LOB locator
Returns:	Error code (0: success) CCI_ER_INVALID_LOB_HANDLE

cci_clob_new¶

int cci_clob_new(int conn_handle, T_CCI_CLOB* clob, T_CCI_ERROR* error_buf)¶

The cci_clob_new function creates an empty file where LOB data is stored and returns locator referring to the data to clob struct.

Parameters:	conn_handle -- ((IN) Connection handle clob -- (OUT) LOB locator error_buf -- (OUT) Error buffer
Returns:	Error code (0: success) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_USED_CONNECTION

cci_clob_read¶

int cci_clob_read(int conn_handle, T_CCI_CLOB clob, long start_pos, int length, char *buf, T_CCI_ERROR* error_buf)¶

The cci_clob_read function reads as much as data from start_pos to length in the LOB data file specified in clob; then it stores it in buf and returns it.

Parameters:	conn_handle -- (IN) Connection handle clob -- (IN) LOB locator start_pos -- (IN) Index location of LOB data file length -- (IN) LOB data length from buffer buf -- (IN) Data buffer to read error_buf -- (OUT) Error buffer
Returns:	Size of read value (>= 0: success), Error code (< 0: Error) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_INVALID_LOB_READ_POS CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

cci_clob_size¶

long long cci_clob_size(T_CCI_CLOB* clob)¶

The cci_clob_size function returns data file size that is specified in clob.

Parameters:	clob -- (IN) LOB locator
Returns:	Size of CLOB data file (>= 0: success), Error code (< 0: error) CCI_ER_INVALID_LOB_HANDLE

cci_clob_write¶

int cci_clob_write(int conn_handle, T_CCI_CLOB clob, long start_pos, int length, const char *buf, T_CCI_ERROR* error_buf)¶

The cci_clob_write function reads as much as data from buf to length and then stores the value from start_pos in LOB data file specified in clob.

Parameters:	conn_handle -- (IN) Connection handle clob -- (IN) LOB locator start_pos -- (IN) Index location of LOB data file length -- (IN) Data length from buffer buf -- (OUT) Data buffer to write error_buf -- (OUT) Error buffer
Returns:	Size of written value (>= 0: success), Error code (< 0: Error) CCI_ER_COMMUNICATION CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_INVALID_LOB_HANDLE CCI_ER_LOGIN_TIMEOUT CCI_ER_NO_MORE_MEMORY CCI_ER_QUERY_TIMEOUT CCI_ER_USED_CONNECTION

cci_close_query_result¶

int cci_close_query_result(int req_handle, T_CCI_ERROR *err_buf)¶

The cci_close_query_result funciton closes the resultset returned by cci_execute(), cci_execute_array() or cci_execute_batch(). If you run cci_prepare() repeatedly without closing the request handle(req_handle), it is recommended to call this function before calling cci_close_req_handle().

Parameters:	req_handle -- (IN) Request handle err_buf -- (OUT) Error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_COMMUNICATION CCI_ER_DBMS CCI_ER_NO_MORE_MEMORY CCI_ER_REQ_HANDLE CCI_ER_RESULT_SET_CLOSED CCI_ER_USED_CONNECTION

cci_close_req_handle¶

int cci_close_req_handle(int req_handle)¶

The cci_close_req_handle function closes the request handle obtained by cci_prepare().

Parameters:	req_handle -- (IN) Request handle
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_REQ_HANDLE CCI_ER_COMMUNICATION CCI_ER_DBMS CCI_ER_NO_MORE_MEMORY CCI_ER_USED_CONNECTION

cci_col_get¶

int cci_col_get(int conn_handle, char *oid_str, char *col_attr, int *col_size, int *col_type, T_CCI_ERROR *err_buf)¶

The cci_col_get function gets an attribute value of collection type. If the name of the class is C, and the domain of set_attr is set (multiset, sequence), the query looks like as follows:

SELECT a FROM C, TABLE(set_attr) AS t(a) WHERE C = oid;

That is, the number of members becomes the number of records.

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid col_attr -- (IN) Collection attribute name col_size -- (OUT) Collection size (-1 : null) col_type -- (OUT) Collection type (set, multiset, sequence: u_type) err_buf -- (OUT) Database error buffer
Returns:	Request handle CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

cci_col_seq_drop¶

int cci_col_seq_drop(int conn_handle, char *oid_str, char *col_attr, int index, T_CCI_ERROR *err_buf)¶

The cci_col_seq_drop function drops the index-th (base: 1) member of the sequence attribute values. The following example shows how to drop the first member of the sequence attribute values.

cci_col_seq_drop(conn_handle, oid_str, seq_attr, 1, err_buf);

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid col_attr -- (IN) Collection attribute name index -- (IN) Index err_buf -- (OUT) Database error buffer
Returns:	Error code CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

cci_col_seq_insert¶

int cci_col_seq_insert(int conn_handle, char *oid_str, char *col_attr, int index, char *value, T_CCI_ERROR *err_buf)¶

The cci_col_seq_insert function inserts one member at the index-th (base: 1) position of the sequence attribute values. The following example shows how to insert "a" at the first position of the sequence attribute values.

cci_col_seq_insert(conn_handle, oid_str, seq_attr, 1, "a", err_buf);

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid col_attr -- (IN) Collection attribute name index -- (IN) Index value -- (IN) Sequential element (string) err_buf -- (OUT) Database error buffer
Returns:	Error code CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

cci_col_seq_put¶

int cci_col_seq_put(int conn_handle, char *oid_str, char *col_attr, int index, char *value, T_CCI_ERROR *err_buf)¶

The cci_col_seq_put function replaces the index-th (base: 1) member of the sequence attribute values with a new value. The following example shows how to replace the first member of the sequence attributes values with "a".

cci_col_seq_put(conn_handle, oid_str, seq_attr, 1, "a", err_buf);

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid col_attr -- (IN) Collection attribute name index -- (IN) Index value -- (IN) Sequential value err_buf -- (OUT) Database error buffer
Returns:	Error code CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

cci_col_set_add¶

int cci_col_set_add(int conn_handle, char *oid_str, char *col_attr, char *value, T_CCI_ERRROR *err_buf)¶

The cci_col_set_add function adds one member to the set attribute values. The following example shows how to add "a" to the set attribute values.

cci_col_set_add(conn_handle, oid_str, set_attr, "a", err_buf);

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid col_attr -- (IN) collection attribute name value -- (IN) set element err_buf -- (OUT) Database error buffer
Returns:	Error code CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

cci_col_set_drop¶

int cci_col_set_drop(int conn_handle, char *oid_str, char *col_attr, char *value, T_CCI_ERROR *err_buf)¶

The cci_col_set_drop function drops one member from the set attribute values. The following example shows how to drop "a" from the set attribute values.

cci_col_set_drop(conn_handle, oid_str, set_attr, "a", err_buf);

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid col_attr -- (IN) collection attribute name value -- (IN) set element (string) err_buf -- (OUT) Database error buffer
Returns:	Error code CCI_ER_CON_HANDLE CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT CCI_ER_COMMUNICATION

cci_col_size¶

int cci_col_size(int conn_handle, char *oid_str, char *col_attr, int *col_size, T_CCI_ERROR *err_buf)¶

The cci_col_size function gets the size of the set (seq) attribute.

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid col_attr -- (IN) Collection attribute name col_size -- (OUT) Collection size (-1: NULL) err_buf -- Database error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

cci_connect¶

int cci_connect(char *ip, int port, char *db_name, char *db_user, char *db_password)¶

A connection handle to the database server is assigned and it tries to connect to the server. If it has succeeded, the connection handle ID is returned; if fails, an error code is returned.

Parameters:	ip -- (IN) A string that represents the IP address of the server (host name) port -- (IN) Broker port (The port configured in the $CUBRID/conf/cubrid_broker.conf file) db_name -- (IN) Database name db_user -- (IN) Database user name db_passwd -- (IN) Database user password
Returns:	Success: Connection handle ID (int), Failure: Error code CCI_ER_NO_MORE_MEMORY CCI_ER_HOSTNAME CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_CONNECT

cci_connect_ex¶

int cci_connect_ex(char *ip, int port, char *db_name, char *db_user, char *db_password, T_CCI_ERROR * err_buf)¶

The cci_connect_ex function returns CCI_ER_DBMS error and checks the error details in the database error buffer (err_buf) at the same time. In that point, it is different from cci_connect() and the others are the same as the cci_connect() function.

Parameters:	ip -- (IN) A string that represents the IP address of the server (host name) port -- (IN) Broker port (The port configured in the $CUBRID/conf/cubrid_broker.conf file) db_name -- (IN) Database name db_user -- (IN) Database user name db_passwd -- (IN) Database user password err_buf -- Database error buffer
Returns:	Success: Connection handle ID (int), Failure: Error code CCI_ER_NO_MORE_MEMORY CCI_ER_HOSTNAME CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_CONNECT

cci_connect_with_url¶

int cci_connect_with_url(char *url, char *db_user, char *db_password)¶

The cci_connect_with_url function connects a database by using connection information passed with a url argument. If broker's HA feature is used in CCI, you must specify the connection information of the standby broker server with altHosts property, which is used for the failover, in the url argument of this function. It returns the ID of a connection handle on success; it returns an error code on failure. For details about HA features of broker, see Duplexing Brokers.

Parameters:

url -- (IN) A string that contains server connection information. db_user -- (IN) Database user name. If this is NULL, it becomes <db_user> in url. If this is an empty string ("") or <db_user> in url is not specified, DB user name becomes PUBLIC. db_passwd -- (IN) Database user password. If this is NULL, <db_password> in url is used. If <db_password> in url is not specified, DB password becomes an empty string ("").

Returns:

Success: Connection handle ID (int), Failure: Error code CCI_ER_NO_MORE_MEMORY CCI_ER_HOSTNAME CCI_ER_INVALID_URL CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_LOGIN_TIMEOUT

<url> ::= cci:CUBRID:<host>:<port>:<db_name>:<db_user>:<db_password>:[?<properties>]

<properties> ::= <property> [&<property>]
<property> ::= altHosts=<alternative_hosts> [ &rcTime=<time>] [ &loadBalance=true|false]
             |{login_timeout|loginTimeout}=<milli_sec>
             |{query_timeout|queryTimeout}=<milli_sec>
             |{disconnect_on_query_timeout|disconnectOnQueryTimeout}=true|false
             | logFile=<file_name>
             | logBaseDir=<dir_name>
             | logSlowQueries=true|false[&slowQueryThresholdMillis=<milli_sec>]
             | logTraceApi=true|false
             | logTraceNetwork=true|false

<alternative_hosts> ::= <host>:<port> [,<host>:<port>]

<host> := HOSTNAME | IP_ADDR
<time> := SECOND
<milli_sec> := MILLI SECOND

altHosts is the property related to connection target and loginTimeout, queryTimeout, and disconnectOnQueryTimeout are the properties related to timeout; logSlowQueries, logTraceApi, and logTraceNetwork are the properties related to log information configuration for debugging. Note that a property name which is a value to be entered in the url argument is not case sensitive.

• host: A host name or IP address of the master database

• port: A port number

• db_name: A name of the database

• db_user: A name of the database user

• db_password: A database user password. You cannot include ':' in the password of the url string.

• altHosts = standby_broker1_host, standby_broker2_host, ...: Specifies the broker information of the standby server, which is used for failover when it is impossible to connect to the active server. You can specify multiple brokers for failover, and the connection to the brokers is attempted in the order listed in alhosts.

  Note

  Even if there are RW and RO together in ACCESS_MODE* setting of brokers of main host and altHosts, application decides the target host to access without the relation for the setting of ACCESS_MODE. Therefore, you should define the main host and altHosts as considering ACCESS_MODE of target brokers.

• rcTime: After the failure occurred on the first connected broker, the application connects to the broker specified by altHosts(broker failover). Then it attempts to reconnect to the first connected broker at every rcTime(default value: 600 seconds).

• loadBalance: When this value is true, the applications try to connect to the main host and alternative hosts specified with the altHosts property as a random order. (default value: false).

• login_timeout | loginTimeout: Timeout value (unit: msec.) for database login. Upon timeout, a CCI_ER_LOGIN_TIMEOUT (-38) error is returned. The default value is 30,000(30 sec.). If this value is 0, it means infinite waiting. This value is also applied when internal reconnection occurs after the initial connection.

• query_timeout | queryTimeout: If time specified in these properties has expired when calling cci_prepare(), cci_execute(), etc. a cancellation message for query request which was sent to a server will be delivered and called function returns a CCI_ER_QUERY_TIMEOUT (-39) error. The value returned upon timeout may vary depending on a value specified in disconnect_on_query_timeout. For details, see disconnect_on_query_timeout.

  Note

  If you use cci_execute_batch() or cci_execute_array()function, or set CCI_EXEC_QUERY_ALL in cci_execute() function to run multiple queries at once, query timeout is applied to one function, not to one query. In other words, if query timeout occurs after the start of a function, a function running is quit.

• disconnect_on_query_timeout | disconnectOnQueryTimeout: Whether to disconnect socket immediately after time for query request has expired. It determines whether to terminate a socket connection immediately or wait for server response after sending cancellation message for query request to a server when calling cci_prepare(), cci_execute(), etc. The default value is false, meaning that it will wait for server response. It this value is true, a socket will be closed immediately after sending a cancellation message to a server upon timeout and returns the CCI_ER_QUERY_TIMEOUT (-39) error. (If an error occurs on database server side, not on broker side, it returns -1. If you want to view error details, see error codes in "database error buffer." You can get information how to check error codes in CCI Error Codes and Error Messages.) Please note that there is a possibility that a database server does not get a cancellation message and execute a query even after an error is returned.

• logFile: A log file name for debugging (default value: cci_ <handle_id> .log). <handle_id> indicates the ID of a connection handle returned by this function.

• logBaseDir: A directory where a debug log file is created. The file name including the path will be logBaseDir/logFile, and the relative path is possible.

• logSlowQueries: Whether to log slow query for debugging (default value: false)

• slowQueryThresholdMillis: Timeout for slow query logging if slow query logging is enabled (default value: 60000, unit: milliseconds)

• logTraceApi: Whether to log the start and end of CCI functions

• logTraceNetwork: Whether to log network data content transferred of CCI functions

Example

--connection URL string when a property(altHosts) is specified for HA
URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000

--connection URL string when properties(altHosts,rcTime) is specified for HA
URL=cci:CUBRID:192.168.0.1:33000:demodb:::?altHosts=192.168.0.2:33000,192.168.0.3:33000&rcTime=600

--connection URL string when properties(logSlowQueries,slowQueryThresholdMills, logTraceApi, logTraceNetwork) are specified for interface debugging
URL = "cci:cubrid:192.168.0.1:33000:demodb:::?logSlowQueries=true&slowQueryThresholdMillis=1000&logTraceApi=true&logTraceNetwork=true"

cci_connect_with_url_ex¶

int cci_connect_with_url_ex(char *url, char *db_user, char *db_password, T_CCI_ERROR * err_buf)¶

The cci_connect_with_url_ex function returns CCI_ER_DBMS error and checks the error details in the database error buffer (err_buf) at the same time. In that point, it is different from cci_connect_with_url() and the others are the same as the cci_connect_with_url() function.

Parameters:	err_buf -- Database error buffer

int cci_cursor(int req_handle, int offset, T_CCI_CURSOR_POS origin, T_CCI_ERROR *err_buf)¶

The cci_cursor function moves the cursor specified in the request handle to access the specific record in the query result executed by cci_execute(). The position of cursor is moved by the values specified in the origin and offset values. If the position to be moved is not valid, CCI_ER_NO_MORE_DATA is returned.

Parameters:	req_handle -- (IN) Request handle offset -- (IN) Offset to be moved origin -- (IN) Variable to represent a position. The type is T_CCI_CURSOR_POS. T_CCI_CURSOR_POS enum consists of CCI_CURSOR_FIRST, CCI_CURSOR_CURRENT and CCI_CURSOR_LAST. err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_REQ_HANDLE CCI_ER_NO_MORE_DATA CCI_ER_COMMUNICATION

Example

//the cursor moves to the first record
cci_cursor(req, 1, CCI_CURSOR_FIRST, &err_buf);

//the cursor moves to the next record
cci_cursor(req, 1, CCI_CURSOR_CURRENT, &err_buf);

//the cursor moves to the last record
cci_cursor(req, 1, CCI_CURSOR_LAST, &err_buf);

//the cursor moves to the previous record
cci_cursor(req, -1, CCI_CURSOR_CURRENT, &err_buf);

cci_cursor_update¶

int cci_cursor_update(int req_handle, int cursor_pos, int index, T_CCI_A_TYPE a_type, void *value, T_CCI_ERROR *err_buf)¶

The cci_cursor_update function updates cursor_pos from the value of the index -th column to value. If the database is updated to NULL, value becomes NULL. For update conditions, see cci_prepare(). The data types of value for a_type are shown in the table below.

Parameters:	req_handle -- (IN) Request handle cursor_pos -- (IN) Cursor position index -- (IN) Column index a_type -- (IN) value Type value -- (IN) A new value err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_REQ_HANDLE CCI_ER_TYPE_CONVERSION CCI_ER_ATYPE

Data types of value for a_type are as below.

a_type	value type
CCI_A_TYPE_STR	char *
CCI_A_TYPE_INT	int *
CCI_A_TYPE_FLOAT	float *
CCI_A_TYPE_DOUBLE	double *
CCI_A_TYPE_BIT	T_CCI_BIT *
CCI_A_TYPE_SET	T_CCI_SET
CCI_A_TYPE_DATE	T_CCI_DATE *
CCI_A_TYPE_BIGINT	int64_t * (For Windows: __int64 *)
CCI_A_TYPE_BLOB	T_CCI_BLOB
CCI_A_TYPE_CLOB	T_CCI_CLOB

cci_datasource_borrow¶

T_CCI_CONN cci_datasource_borrow(T_CCI_DATASOURCE *datasource, T_CCI_ERROR *err_buf)¶

The cci_datasource_borrow function obtains CCI connection to be used in T_CCI_DATASOURCE struct.

Parameters:	datasource -- (IN) T_CCI_DATASOURCE struct pointer in which CCI connection exists err_buf -- (OUT) Error code and message returned upon error occurrence
Returns:	Success: CCI connection handler identifier, Failure: -1

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_destroy(), cci_datasource_release(), cci_datasource_change_property()

cci_datasource_change_property¶

int cci_datasource_change_property(T_CCI_DATASOURCE *datasource, const char *key, const char *val)¶

A property name of a DATASOURCE is specified in key, a value in val. The changed property value by this function is applied to all connections in the datasource.

Parameters:	datasource -- (IN) T_CCI_DATASOURCE struct pointer to obtain CCI connections. key -- (IN) A pointer to the string of a property name val -- (IN) A pointer to the string of a property value
Returns:	Error code(0: success) CCI_ER_NO_MORE_MEMORY CCI_ER_NO_PROPERTY CCI_ER_PROPERTY_TYPE

The following shows names and values of changeable properties.

Property name	Type	Value	Description
default_autocommit	bool	true/false	Whether auto-commit or not. The default is CCI_DEFAULT_AUTOCOMMIT in cubrid_broker.conf; the default of this is ON(true)
default_lock_timeout	msec	number	lock timeout
default_isolation	string	See the table of cci_property_set()	isolation level. The default is isolation_level in cubrid.conf; the default of this is "READ COMMITTED".
login_timeout	msec	number	login timeout. The default is 0(infinite wait). It can also be used when you call prepare or execute functions; at this time reconnection can happen.

Example

...
ps = cci_property_create ();
...
ds = cci_datasource_create (ps, &err);
...
cci_datasource_change_property(ds, "login_timeout", "5000");
cci_datasource_change_property(ds, "default_lock_timeout", "2000");
cci_datasource_change_property(ds, "default_isolation", "TRAN_REP_CLASS_COMMIT_INSTANCE");
cci_datasource_change_property(ds, "default_autocommit", "true");
...

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_borrow(), cci_datasource_destroy(), cci_datasource_release()

cci_datasource_create¶

T_CCI_DATASOURCE * cci_datasource_create(T_CCI_PROPERTIES *properties, T_CCI_ERROR *err_buf)¶

The cci_datasource_create function creates DATASOURCE of CCI.

Parameters:	properties -- (IN) T_CCI_PROPERTIES struct pointer in which configuration of struct pointer is stored. Values of properties will be set with cci_property_set(). err_buf -- (OUT) Error buffer. Error code and message returned upon error occurrence
Returns:	Success: T_CCI_DATASOURCE struct pointer created, Failure: NULL

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_borrow(), cci_datasource_destroy(), cci_datasource_release(), cci_datasource_change_property()

cci_datasource_destroy¶

void cci_datasource_destroy(T_CCI_DATASOURCE *datasource)¶

The cci_datasource_destroy function destroys DATASOURCE of CCI.

Parameters:	datasource -- (IN) T_CCI_DATASOURCE struct pointer to be deleted
Returns:	void

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_borrow(), cci_datasource_release(), cci_datasource_change_property()

cci_datasource_release¶

int cci_datasource_release(T_CCI_DATASOURCE *datasource, T_CCI_CONN conn, T_CCI_ERROR *err_buf)¶

The cci_datasource_release function returns CCI connection released in T_CCI_DATASOURCE struct. If you want to reuse the connection after calling this function, recall cci_datasource_borrow().

Parameters:	datasource -- (IN) T_CCI_DATASOURCE struct pointer which returns CCI connection conn -- (IN) CCI connection handler identifier released err_buf -- (OUT) Error buffer(returns error code and error message when an error occurs)
Returns:	Success: 1, Failure: 0

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_destroy(), cci_datasource_borrow(), cci_datasource_change_property()

cci_disconnect¶

int cci_disconnect(int conn_handle, T_CCI_ERROR *err_buf)¶

The cci_disconnect function disconnects all request handles created for conn_handle. If a transaction is being performed, the handles are disconnected after cci_end_tran() is executed.

Parameters:	conn_handle -- (IN) Connection handle err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION

cci_end_tran¶

int cci_end_tran(int conn_handle, char type, T_CCI_ERROR *err_buf)¶

The cci_end_tran function performs commit or rollback on the current transaction. At this point, all open request handles are terminated and the connection to the database server is disabled. However, even after the connection to the server is disabled, the connection handle remains valid.

Parameters:	conn_handle -- (IN) Connection handle type -- (IN) CCI_TRAN_COMMIT or CCI_TRAN_ROLLBACK err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_TRAN_TYPE

You can configure the default value of auto-commit mode by using CCI_DEFAULT_AUTOCOMMIT broker parameter upon startup of an application. If configuration on broker parameter is omitted, the default value is ON; use the cci_set_autocommit() function to change auto-commit mode within an application. If auto-commit mode is OFF, you must explicitly commit or roll back transaction by using the cci_end_tran() function.

cci_escape_string¶

long cci_escape_string(int conn_handle, char *to, const char *from, unsigned long length, T_CCI_ERROR *err_buf)¶

Converts the input string to a string that can be used in the CUBRID query. The following parameters are specified in this function: connection handle or no_backslash_escapes setting value, output string pointer, input string pointer, the length of the input string, and the address of the T_CCI_ERROR struct variable.

Parameters:

conn_handle -- (IN) connection handle or no_backslash_escapes setting value. When a connection handle is given, the no_backslash_escapes parameter value is read to determine how to convert. Instead of the connection handle, CCI_NO_BACKSLASH_ESCAPES_TRUE or CCI_NO_BACKSLASH_ESCAPES_FALSE value can be sent to determine how to convert. to -- (OUT) Result string from -- (IN) Input string length -- (IN) Maximum byte length of the input string err_buf -- (OUT) Database error buffer

Returns:

Success: Byte length of the changed string, Failure: Error Code CCI_ER_CON_HANDLE CCI_ER_COMMUNICATION

When the system parameter no_backslash_escapes is yes (default) or when the CCI_NO_BACKSLASH_ESCAPES_TRUE value is sent to the connection handle location, the string is converted to the following characters.

• ' (single quote) => ' + ' (escaped single quote)

When the system parameter no_backslash_escapes is no or when the CCI_NO_BACKSLASH_ESCAPES_FALSE value is sent to the connection handle location, the string is converted to the following characters:

• \n (new line character, ASCII 10) => \ + n (backslash + Alphabet n)
• \r (carriage return, ASCII 13) => \ + r (backslash + Alphabet r)
• \0 (ASCII 0) => \ + 0 (backslash + 0(ASCII 48)
• \ (backslash) => \ + \

You can assign the space where the result string will be saved by using the length parameter. It will take as much as the byte length of the maximum input string * 2 + 1.

cci_execute¶

int cci_execute(int req_handle, char flag, int max_col_size, T_CCI_ERROR *err_buf)¶

The cci_execute function executes the SQL statement (prepared statement) that has executed cci_prepare(). A request handle, flag, the maximum length of a column to be fetched, and the address of a T_CCI_ERROR construct variable in which error information being stored are specified as arguments.

Parameters:	req_handle -- (IN) Request handle of the prepared statement flag -- (IN) exec flag ( CCI_EXEC_QUERY_ALL ) max_col_size -- (IN) The maximum length of a column to be fetched when it is a string data type in bytes. If this value is 0, full length is fetched. err_buf -- (OUT) Database error buffer
Returns:	SELECT : Returns the number of results INSERT, UPDATE : Returns the number of rows reflected Others queries : 0 Failure : Error code CCI_ER_REQ_HANDLE CCI_ER_BIND CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT

Through a flag, the way of query execution can be set as all queries or the first one.

Note

In 2008 R4.4 and from 9.2, CUBRID does not support setting the flag as CCI_EXEC_ASYNC, which brings the results as an asynchronous method.

If the flag is set to CCI_EXEC_QUERY_ALL, all prepared queries(separated by semicolon) are executed. If not, only the first query is executed.

If the flag is set to CCI_EXEC_QUERY_ALL, the following rules are applied.

• The return value is the result of the first query.
• If an error occurs in any query, the execution is processed as a failure.
• For a query composed of in a query composed of q1; q2; q3, even if an error occurs in q2 after q1 succeeds the execution, the result of q1 remains valid. That is, the previous successful query executions are not rolled back when an error occurs.
• If a query is executed successfully, the result of the second query can be obtained using cci_next_result().

max_col_size is a value that is used to determine the maximum length of a column to be sent to a client when the columns of the prepared statement are CHAR, VARCHAR, BIT or VARBIT. If this value is 0, full length is fetched.

cci_execute_array¶

int cci_execute_array(int req_handle, T_CCI_QUERY_RESULT **query_result, T_CCI_ERROR *err_buf)¶

If more than one value is bound to the prepared statement, this gets the values of the variables to be bound and executes the query by binding each value to the variable.

Parameters:	req_handle -- (IN) Request handle of the prepared statement query_result -- (OUT) Query results err_buf -- (OUT) Database error buffer
Returns:	Success: The number of executed queries, Failure: Negative number CCI_ER_REQ_HANDLE CCI_ER_BIND CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT

To bind the data, call the cci_bind_param_array_size() function to specify the size of the array, bind each value to the variable by using the cci_bind_param_array() function, and execute the query by calling the cci_execute_array() function. The query result will be stored on the array of T_CCI_QUERY_RESULT structure.

cci_execute_array() function returns the results of queries to the query_result variable. You can use below macros to get the result of each query. In the macro, note that the validation check for each parameter entered is not performed.

After using the query_result variable, you must delete the query_result by using the cci_query_result_free() function.

Macro	Return Type	Description
CCI_QUERY_RESULT_RESULT	int	the number of affected rows or error identifier (-1: CAS error, -2: DBMS error)
CCI_QUERY_RESULT_ERR_NO	int	error number about a query
CCI_QUERY_RESULT_ERR_MSG	char *	error message about a query
CCI_QUERY_RESULT_STMT_TYPE	int(T_CCI_CUBRID_STMT enum)	type of a query statement

If autocommit mode is on, each query in the array is committed after executing.

Note

• In the previous version of 2008 R4.3, if the autocommit mode is on, all queries in the array were committed after all of them are executed. From 2008 R4.3 version, the transaction is committed every time when a query is executed.
• In autocommit mode off, if the general error occurs during executing one of the queries in the array on the cci_execute_array function which does a batch processing of the queries, the query with an error is ignored and the next query is executed continuously. But if the deadlock occurs, the error occurs as rolling back the transaction.

char *query =
    "update participant set gold = ? where host_year = ? and nation_code = 'KOR'";
int gold[2];
char *host_year[2];
int null_ind[2];
T_CCI_QUERY_RESULT *result;
int n_executed;
...

req = cci_prepare (con, query, 0, &cci_error);
if (req < 0)
{
    printf ("prepare error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}

gold[0] = 20;
host_year[0] = "2004";

gold[1] = 15;
host_year[1] = "2008";

null_ind[0] = null_ind[1] = 0;
error = cci_bind_param_array_size (req, 2);
if (error < 0)
{
    printf ("bind_param_array_size error: %d\n", error);
    goto handle_error;
}

error =
    cci_bind_param_array (req, 1, CCI_A_TYPE_INT, gold, null_ind, CCI_U_TYPE_INT);
if (error < 0)
{
    printf ("bind_param_array error: %d\n", error);
    goto handle_error;
}
error =
    cci_bind_param_array (req, 2, CCI_A_TYPE_STR, host_year, null_ind, CCI_U_TYPE_INT);
if (error < 0)
{
    printf ("bind_param_array error: %d\n", error);
    goto handle_error;
}

n_executed = cci_execute_array (req, &result, &cci_error);
if (n_executed < 0)
{
    printf ("execute error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}
for (i = 1; i <= n_executed; i++)
{
    printf ("query %d\n", i);
    printf ("result count = %d\n", CCI_QUERY_RESULT_RESULT (result, i));
    printf ("error message = %s\n", CCI_QUERY_RESULT_ERR_MSG (result, i));
    printf ("statement type = %d\n",
            CCI_QUERY_RESULT_STMT_TYPE (result, i));
}
error = cci_query_result_free (result, n_executed);
if (error < 0)
{
    printf ("query_result_free: %d\n", error);
    goto handle_error;
}
error = cci_end_tran(con, CCI_TRAN_COMMIT, &cci_error);
if (error < 0)
{
    printf ("end_tran: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}

cci_execute_batch¶

int cci_execute_batch(int conn_handle, int num_sql_stmt, char **sql_stmt, T_CCI_QUERY_RESULT **query_result, T_CCI_ERROR *err_buf)¶

In CCI, multiple jobs can be processed simultaneously when using DML queries such as INSERT / UPDATE / DELETE. CCI_QUERY_RESULT_RESULT and cci_execute_batch() functions can be used to execute such batch jobs. Note that prepared statements cannot be used in the cci_execute_batch() function. The query result will be stored on the array of T_CCI_QUERY_RESULT structure.

Parameters:	conn_handle -- (IN) Connection handle num_sql_stmt -- (IN) The number of sql_stmt sql_stmt -- (IN) SQL statement array query_result -- (OUT) The results of sql_stmt err_buf -- (OUT) Database error buffer
Returns:	Success: The number of executed queries, Failure: Negative number CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_NO_MORE_MEMORY CCI_ER_CONNECT CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT

Executes sql_stmt as many times as num_sql_stmt specified as a parameter and returns the number of queries executed with the query_result variable. You can use CCI_QUERY_RESULT_RESULT, c:macro:CCI_QUERY_RESULT_ERR_NO, CCI_QUERY_RESULT_ERR_MSG and CCI_QUERY_RESULT_STMT_TYPE macros to get the result of each query. Regarding the summary of these macros, see the cci_execute_array() function.

Note that the validity check is not performed for each parameter entered in the macro.

After using the query_result variable, you must delete the query result by using the cci_query_result_free() function.

If autocommit mode is on, each query in the array is committed after executing.

Note

• In the previous version of 2008 R4.3, if the autocommit is on, all queries in the array were committed after all of them are executed. From 2008 R4.3 version, each query in the array is committed right after each running.
• If autocommit mode is off, after the general error occurs during executing one of the queries in the array on the cci_execute_batch function which does a batch processing of the queries, the query with an error is ignored and the next query is executed. But if the deadlock occurs, the error occurs as rolling back the transaction.

...
char **queries;
T_CCI_QUERY_RESULT *result;
int n_queries, n_executed;
...
count = 3;
queries = (char **) malloc (count * sizeof (char *));
queries[0] =
    "insert into athlete(name, gender, nation_code, event) values('Ji-sung Park', 'M', 'KOR', 'Soccer')";
queries[1] =
    "insert into athlete(name, gender, nation_code, event) values('Joo-young Park', 'M', 'KOR', 'Soccer')";
queries[2] =
    "select * from athlete order by code desc limit 2";

//calling cci_execute_batch()
n_executed = cci_execute_batch (con, count, queries, &result, &cci_error);
if (n_executed < 0)
{
    printf ("execute_batch: %d, %s\n", cci_error.err_code, cci_error.err_msg);
    goto handle_error;
}
printf ("%d statements were executed.\n", n_executed);

for (i = 1; i <= n_executed; i++)
{
    printf ("query %d\n", i);
    printf ("result count = %d\n", CCI_QUERY_RESULT_RESULT (result, i));
    printf ("error message = %s\n", CCI_QUERY_RESULT_ERR_MSG (result, i));
    printf ("statement type = %d\n",
            CCI_QUERY_RESULT_STMT_TYPE (result, i));
}

error = cci_query_result_free (result, n_executed);
if (error < 0)
{
    printf ("query_result_free: %d\n", error);
    goto handle_error;
}
...

cci_execute_result¶

int cci_execute_result(int req_handle, T_CCI_QUERY_RESULT **query_result, T_CCI_ERROR *err_buf)¶

The cci_execute_result function stores the execution results (e.g. statement type, result count) performed by cci_execute() to the array of T_CCI_QUERY_RESULT structure. You can use CCI_QUERY_RESULT_RESULT, CCI_QUERY_RESULT_ERR_NO, CCI_QUERY_RESULT_ERR_MSG, CCI_QUERY_RESULT_STMT_TYPE macros to get the results of each query. Regarding the summary of these macros, see the cci_execute_array() function.

Note that the validity check is not performed for each parameter entered in the macro.

The memory of used query results must be released by the cci_query_result_free() function.

Parameters:	req_handle -- (IN) Request handle of the prepared statement query_result -- (OUT) Query results err_buf -- (OUT) Database error buffer
Returns:	Success: The number of queries, Failure: Negative number CCI_ER_REQ_HANDLE CCI_ER_COMMUNICATION

...
T_CCI_QUERY_RESULT *qr;
...

cci_execute( ... );
res = cci_execute_result(req_h, &qr, &err_buf);
if (res < 0)
{
    /* error */
}
else
{
    for (i=1 ; i <= res ; i++)
    {
        result_count = CCI_QUERY_RESULT_RESULT(qr, i);
        stmt_type = CCI_QUERY_RESULT_STMT_TYPE(qr, i);
    }
    cci_query_result_free(qr, res);
}
...

cci_fetch¶

int cci_fetch(int req_handle, T_CCI_ERROR *err_buf)¶

The cci_fetch function fetches the query result executed by cci_execute() from the server-side CAS and stores it to the client buffer. The cci_get_data() function can be used to identify the data of a specific column from the fetched query result.

Parameters:	req_handle -- (IN) Request handle err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_REQ_HANDLE CAS_ER_HOLDABLE_NOT_ALLOWED CCI_ER_NO_MORE_DATA CCI_ER_RESULT_SET_CLOSED CCI_ER_DELETED_TUPLE CCI_ER_COMMUNICATION CCI_ER_NO_MORE_MEMORY

cci_fetch_buffer_clear¶

int cci_fetch_buffer_clear(int req_handle)¶

The cci_fetch_buffer_clear function clears the records temporarily stored in the client buffer.

Parameters:	req_handle -- Request handle
Returns:	Error code (0: success) CCI_ER_REQ_HANDLE

cci_fetch_sensitive¶

int cci_fetch_sensitive(int req_handle, T_CCI_ERROR *err_buf)¶

The cci_fetch_sensitive function sends changed values for sensitive column when the SELECT query result is delivered. If the results by req_handle are not sensitive, they are same as the ones by cci_fetch(). The return value of CCI_ER_DELETED_TUPLE means that the given row has been deleted.

Parameters:	req_handle -- (IN) Request handle err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_REQ_HANDLE CCI_ER_NO_MORE_DATA CCI_ER_COMMUNICATION CCI_ER_DBMS CCI_ER_DELETED_TUPLE

sensitive column means the item that can provide updated value in the SELECT list when you re-request the results. For example, if a column is directly used as an item of the SELECT list without aggregation operation, this column can be called a sensitive column.

When you fetch the result again, the sensitive result receive the data from the server, not from the client buffer.

cci_fetch_size¶

int cci_fetch_size(int req_handle, int fetch_size)¶

This function is deprecated. Even if it's called, there will be ignored.

cci_get_autocommit¶

CCI_AUTOCOMMIT_MODE cci_get_autocommit(int conn_handle)¶

The cci_get_autocommit function returns the auto-commit mode currently configured.

Parameters:	conn_handle -- (IN) Connection handle
Returns:	CCI_AUTOCOMMIT_TRUE: Auto-commit mode is ON CCI_AUTOCOMMIT_FALSE: Auto-commit mode is OFF CCI_ER_CON_HANDLE CCI_ER_USED_CONNECTION

cci_get_bind_num¶

int cci_get_bind_num(int req_handle)¶

The cci_get_bind_num function gets the number of input bindings. If the SQL statement used during preparation is composed of multiple queries, it represents the number of input bindings used in all queries.

Parameters:	req_handle -- (IN) Request handle for the prepared statement
Returns:	The number of input bindings CCI_ER_REQ_HANDLE

cci_get_cas_info¶

int cci_get_cas_info(int conn_handle, char *info_buf, int buf_length, T_CCI_ERROR * err_buf)¶

Retrieve CAS information which is connected to conn_handle. The string of the below format is returned to the info_buf.

<host>:<port>,<cas id>,<cas process id>

The below is an example.

127.0.0.1:33000,1,12916

Through CAS ID, you can check the SQL log file of this CAS easily.

For details, see Checking SQL Log.

Parameters:	conn_handle -- (IN) connection handle info_buf -- (OUT) connection information buffer buf_length -- (IN) buffer length of the connection information err_buf -- (OUT) Error buffer
Returns:	error code CCI_ER_INVALID_ARGS CCI_ER_CON_HANDLE

cci_get_class_num_objs¶

int cci_get_class_num_objs(int conn_handle, char *class_name, int flag, int *num_objs, int *num_pages, T_CCI_ERROR *err_buf)¶

The cci_get_class_num_objs function gets the number of objects of the class_name class and the number of pages being used. If the flag is configured to 1, an approximate value is fetched; if it is configured to 0, an exact value is fetched.

Parameters:	conn_handle -- (IN) Connection handle class_name -- (IN) Class name flag -- (IN) 0 or 1 num_objs -- (OUT) The number of objects num_pages -- (OUT) The number of pages err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_REQ_HANDLE CCI_ER_COMMUNICATION CCI_ER_CONNECT

CCI_GET_COLLECTION_DOMAIN¶

#define CCI_GET_COLLECTION_DOMAIN(u_type)¶

If u_type is set, multiset, or sequence type, this macro gets the domain of the set, multiset or sequence. If u_type is not a set type, the return value is the same as u_type.

Returns:	Type (CCI_U_TYPE)

cci_get_cur_oid¶

int cci_get_cur_oid(int req_handle, char *oid_str_buf)¶

The cci_get_cur_oid function gets OID of the currently fetched records if CCI_INCLUDE_OID is configured in execution. The OID is represented in string for a page, slot, or volume.

Parameters:	conn_handle -- (IN) Request handle oid_str_buf -- (OUT) OID string
Returns:	Error code (0: success) CCI_ER_REQ_HANDLE

cci_get_data¶

int cci_get_data(int req_handle, int col_no, int type, void *value, int *indicator)¶

The cci_get_data function gets the col_no -th value from the currently fetched result.

Parameters:

req_handle -- (IN) Request handle col_no -- (IN) One-based column index. It starts with 1. type -- (IN) Data type (defined in the T_CCI_A_TYPE) of value variable value -- (OUT) Variable address for data to be stored. If type is one of (CCI_A_TYPE_STR, CCI_A_TYPE_SET, CCI_A_TYPE_BLOB or CCI_A_TYPE_CLOB) and the value of a column is NULL, the value will be NULL, too. indicator -- (OUT) NULL indicator. (-1 : NULL) If type is CCI_A_TYPE_STR : -1 is returned in case of NULL; the length of string stored in value is returned, otherwise. If type is not CCI_A_TYPE_STR : -1 is returned in case of NULL, 0 is returned, otherwise.

Returns:

Error code (0: success) CCI_ER_REQ_HANDLE CCI_ER_TYPE_CONVERSION CCI_ER_COLUMN_INDEX CCI_ER_ATYPE

The type of the value variable is determined based on the given type argument, and the value or the pointer is copied to the value variable accordingly. For a value to be copied, the memory for the address to be transferred to the value variable must have been previously assigned. Note that if a pointer is copied, a pointer in the application client library is returned, so the value becomes invalid next time the cci_get_data() function is called.

In addition, the pointer returned by the pointer copy must not be freed. However, if the type is CCI_A_TYPE_SET, the memory must be freed by using the cci_set_free() function after using the set because the set is returned after the T_CCI_SET type memory is allocated. The following table shows the summary of type arguments and data types of their corresponding value values.

type	value Type	Meaning
CCI_A_TYPE_STR	char **	pointer copy
CCI_A_TYPE_INT	int *	value copy
CCI_A_TYPE_FLOAT	float *	value copy
CCI_A_TYPE_DOUBLE	double *	value copy
CCI_A_TYPE_BIT	T_CCI_BIT *	value copy (pointer copy for each member)
CCI_A_TYPE_SET	T_CCI_SET *	memory allocation and value copy
CCI_A_TYPE_DATE	T_CCI_DATE *	value copy
CCI_A_TYPE_BIGINT	int64_t * (For Windows: __int64 *)	value copy
CCI_A_TYPE_BLOB	T_CCI_BLOB *	memory allocation and value copy
CCI_A_TYPE_CLOB	T_CCI_CLOB *	memory allocation and value copy

Remark

• For LOB type, if the cci_get_data() function is called, meta data with the LOB type column (locator) is displayed. To call data of the LOB type column, the cci_blob_read() function should be called.

The below example shows a part of a code to print out the fetched result with cci_get_data().

...

if ((res=cci_get_data(req, i, CCI_A_TYPE_INT, &buffer, &ind))<0) {
    printf( "%s(%d): cci_get_data fail\n", __FILE__, __LINE__);
    goto handle_error;
}
if (ind != -1)
        printf("%d \t|", buffer);
else
        printf("NULL \t|");
...

cci_get_db_parameter¶

int cci_get_db_parameter(int conn_handle, T_CCI_DB_PARAM param_name, void *value, T_CCI_ERROR *err_buf)¶

The cci_get_db_parameter function gets a parameter value specified in the database.

Parameters:	conn_handle -- (IN) Connection handle param_name -- (IN) System parameter name value -- (OUT) Parameter value err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_PARAM_NAME CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_CONNECT

The data type of value for param_name is shown in the table below.

param_name	value Type	note
CCI_PARAM_ISOLATION_LEVEL	int *	get/set
CCI_PARAM_LOCK_TIMEOUT	int *	get/set
CCI_PARAM_MAX_STRING_LENGTH	int *	get only

In cci_get_db_parameter() and cci_set_db_parameter(), the input/output unit of CCI_PARAM_LOCK_TIMEOUT is milliseconds.

Warning

In the earlier version of CUBRID 9.0, you should be careful that the output unit of CCI_PARAM_LOCK_TIMEOUT is second.

CCI_PARAM_MAX_STRING_LENGTH is measured in bytes and it gets a value defined in the MAX_STRING_LENGTH broker parameter.

cci_get_db_version¶

int cci_get_db_version(int conn_handle, char *out_buf, int out_buf_size)¶

The cci_get_db_version function gets the Database Management System (DBMS) version.

Parameters:	conn_handle -- (IN) Connection handle out_buf -- (OUT) Result buffer out_buf_size -- (IN) out_buf size
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_COMMUNICATION CCI_ER_CONNECT

cci_get_err_msg¶

int cci_get_err_msg(int err_code, char *msg_buf, int msg_buf_size)¶

The cci_get_err_msg function stores error messages corresponding to the error code in the error message buffer. For details on error codes and error messages, see CCI Error Codes and Error Messages.

Parameters:	err_code -- (IN) Error code msg_buf -- (OUT) Error message buffer msg_buf_size -- (IN) msg_buf size
Returns:	0: Success, -1: Failure

note:: From CUBRID 9.1, CUBRID ensures that all functions which have err_buf parameter store an error value into err_buf parameter, so you don't need to use cci_get_err_msg function if a function has err_buf parameter.

req = cci_prepare (con, query, 0, &err_buf);
if (req < 0)
{
    printf ("error: %d, %s\n", err_buf.err_code, err_buf.err_msg);
    goto handle_error;
}

On the previous version of 9.1, an err_buf value was stored only when CCI_ER_DBMS error occurred. So printing an error message should have been separated by CCI_ER_DBMS error.

req = cci_prepare (con, query, 0, &err_buf);
if (req < 0)
{
    if (req == CCI_ER_DBMS)
    {
        printf ("error: %s\n", err_buf.err_msg);
    }
    else
    {
        char msg_buf[1024];
        cci_get_err_msg(req, msg_buf, 1024);
        printf ("error: %s\n", msg_buf);
    }
    goto handle_error;
}

From 9.1, you can simplify the branch of the above code by using cci_get_error_msg function.

req = cci_prepare (con, query, 0, &err_buf);
if (req < 0)
{
    char msg_buf[1024];
    cci_get_error_msg(req, err_buf, msg_buf, 1024);
    printf ("error: %s\n", msg_buf);
    goto handle_error;
}

cci_get_error_msg¶

int cci_get_error_msg(int err_code, T_CCI_ERROR *err_buf, char *msg_buf, int msg_buf_size)¶

Saves the error messages corresponding to the CCI error codes in the message buffer. If the value of CCI error code is CCI_ER_DBMS, the database error buffer (err_buf) receives the error message sent from the data server and saves it in the message buffer(msg_buf). For details on error codes and messages, see CCI Error Codes and Error Messages.

Parameters:	err_code -- (IN) Error code err_buf -- (IN) Database error buffer msg_buf -- (OUT) Error message buffer msg_buf_size -- (IN) msg_buf size
Returns:	0: Success, -1: Failure

cci_get_holdability¶

int cci_get_holdability(int conn_handle)¶

Returns the cursor holdability setting value about the result set from the connection handle. When it is 1, the connection is disconnected or the cursor is holdable until the result set is intentionally closed regardless of commit. When it is 0, the result set is closed when committed and the cursor is not holdable. For more details on cursor holdability, see Cursor Holdability.

Parameters:	conn_handle -- (IN) Connection handle
Returns:	0 (not holdable), 1 (holdable) CCI_ER_CON_HANDLE

cci_get_last_insert_id¶

int cci_get_last_insert_id(int conn_handle, void *value, T_CCI_ERROR *err_buf)¶

Gets the primary key of the INSERT statement which executed at the last time.

Parameters:	conn_handle -- (IN) Request handle value -- (OUT) The pointer of the result buffer pointer(char **). It stores the last primary key of INSERT statement executed on the last time. The memory which this pointer indicates doesn't need to be released, because it is the fixed buffer inside the connection handle. err_buf -- (OUT) Error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_USED_CONNECTION CCI_ER_INVALID_ARGS

#include <stdio.h>
#include "cas_cci.h"

int main ()
{
    int con = 0;
    int req = 0;

    int error;
    T_CCI_ERROR cci_error;


    char *query = "insert into t1 values(NULL);";
    char *value = NULL;

    con = cci_connect ("localhost", 33000, "demodb", "dba", "");

    if (con < 0)
    {
        printf ("con error\n");
        return;
    }

    req = cci_prepare (con, query, 0, &cci_error);
    if (req < 0)
    {
        printf ("cci_prepare error: %d\n", req);
        printf ("cci_error: %d, %s\n", cci_error.err_code, cci_error.err_msg);
        return;
    }
    error = cci_execute (req, 0, 0, &cci_error);
    if (error < 0)
    {
        printf ("cci_execute error: %d\n", error);
        return;
    }

    error = cci_get_last_insert_id (con, &value, &cci_error);
    if (error < 0)
    {
        printf ("cci_get_last_insert_id error: %d\n", error);
        return;
    }

    printf ("## last insert id: %s\n", value);

    error = cci_close_req_handle (req);
    error = cci_disconnect (con, &cci_error);
    return 0;
}

cci_get_login_timeout¶

int cci_get_login_timeout(int conn_handle, int *timeout, T_CCI_ERROR *err_buf)¶

Return login timeout value to timeout.

Parameters:	conn_handle -- (IN) Connection handle timeout -- (OUT) A pointer to login timeout value(unit: millisecond) err_buf -- (OUT) Error buffer
Returns:	Error code (0: success) CCI_ER_INVALID_ARGS CCI_ER_CON_HANDLE CCI_ER_USED_CONNECTION

cci_get_query_plan¶

int cci_get_query_plan(int req_handle, char **out_buf_p)¶

Saves the query plan to the result buffer; the query plan about the request handle which the cci_prepare function returned. You can call this function whether to call the cci_execute function or not.

After calling the cci_get_query_plan function, if the use of a result buffer ends, you should call the cci_query_info_free() function to release the result buffer created by cci_get_query_plan function.

char *out_buf;
...
req = cci_prepare (con, query, 0, &cci_error);
...
ret = cci_get_query_plan(req, &out_buf);
...
printf("plan = %s", out_buf);
cci_query_info_free(out_buf);

Parameters:	req_handle -- (IN) Request handle out_buf_p -- (OUT) The pointer of a result buffer pointer
Returns:	Error code CCI_ER_REQ_HANDLE CCI_ER_CON_HANDLE CCI_ER_USED_CONNECTION

See also

cci_query_info_free()

cci_query_info_free¶

int cci_query_info_free(char *out_buf)¶

Releases the result buffer memory allocated from the cci_get_query_plan() function.

Parameters:	req_handle -- (IN) Request handle out_buf -- (OUT) Result buffer pointer
Returns:	Error code CCI_ER_NO_MORE_MEMORY

See also

cci_get_query_plan()

cci_get_query_timeout¶

int cci_get_query_timeout(int req_handle)¶

The cci_get_query_timeout function returns timeout configured for query execution.

Parameters:	req_handle -- (IN) Request handle
Returns:	Success: Timeout value configured in current request handle (unit: msec.), Failure: Error code CCI_ER_REQ_HANDLE

cci_get_result_info¶

T_CCI_COL_INFO* cci_get_result_info(int req_handle, T_CCI_CUBRID_STMT *stmt_type, int *num)¶

If the prepared statement is SELECT, the T_CCI_COL_INFO struct that stores the column information about the execution result can be obtained by using this function. If it is not SELECT, NULL is returned and the num value becomes 0.

Parameters:	req_handle -- (IN) Request handle for the prepared statement stmt_type -- (OUT) Command type num -- (OUT) he number of columns in the SELECT statement (if stmt_type is CUBRID_STMT_SELECT)
Returns:	Success: Result info pointer, Failure: NULL

You can access the T_CCI_COL_INFO struct directly to get the column information from the struct, but you can also use a macro to get the information, which is defined as follows. The address of the T_CCI_COL_INFO struct and the column index are specified as parameters for each macro. The macro can be called only for the SELECT query. Note that the validity check is not performed for each parameter entered in each macro. If the return type of the macro is char*, do not free the memory pointer.

Macro	Return Type	Meaning
CCI_GET_RESULT_INFO_TYPE	T_CCI_U_TYPE	column type
CCI_GET_RESULT_INFO_SCALE	short	column scale
CCI_GET_RESULT_INFO_PRECISION	int	column precision
CCI_GET_RESULT_INFO_NAME	char *	column name
CCI_GET_RESULT_INFO_ATTR_NAME	char *	column attribute name
CCI_GET_RESULT_INFO_CLASS_NAME	char *	column class name
CCI_GET_RESULT_INFO_IS_NON_NULL	char (0 or 1)	whether a column is NULL

col_info = cci_get_result_info (req, &stmt_type, &col_count);
if (col_info == NULL)
{
  printf ("get_result_info error\n");
  goto handle_error;
}

for (i = 1; i <= col_count; i++)
{
  printf ("%-12s = %d\n", "type", CCI_GET_RESULT_INFO_TYPE (col_info, i));
  printf ("%-12s = %d\n", "scale",
          CCI_GET_RESULT_INFO_SCALE (col_info, i));
  printf ("%-12s = %d\n", "precision",
          CCI_GET_RESULT_INFO_PRECISION (col_info, i));
  printf ("%-12s = %s\n", "name", CCI_GET_RESULT_INFO_NAME (col_info, i));
  printf ("%-12s = %s\n", "attr_name",
          CCI_GET_RESULT_INFO_ATTR_NAME (col_info, i));
  printf ("%-12s = %s\n", "class_name",
          CCI_GET_RESULT_INFO_CLASS_NAME (col_info, i));
  printf ("%-12s = %s\n", "is_non_null",
          CCI_GET_RESULT_INFO_IS_NON_NULL (col_info,i) ? "true" : "false");
}

CCI_GET_RESULT_INFO_ATTR_NAME¶

#define CCI_GET_RESULT_INFO_ATTR_NAME(T_CCI_COL_INFO* res_info, int index)¶

The CCI_GET_RESULT_INFO_ATTR_NAME macro gets the actual attribute name of the index-th column of a prepared SELECT list. If there is no name for the attribute (constant, function, etc), " " (empty string) is returned. It does not check whether the specified argument, res_info, is NULL and whether index is valid. You cannot delete the returned memory pointer with free().

Parameters:	res_info -- (IN) A pointer to the column information fetched by cci_get_result_info() index -- (IN) Column index
Returns:	Attribute name (char *)

CCI_GET_RESULT_INFO_CLASS_NAME¶

#define CCI_GET_RESULT_INFO_CLASS_NAME(T_CCI_COL_INFO* res_info, int index)¶

The CCI_GET_RESULT_INFO_CLASS_NAME macro gets the index-th column's class name of a prepared SELECT list. It does not check whether the specified argument, res_info, is NULL and whether index is valid. You cannot delete the returned memory pointer with free (). The return value can be NULL.

Parameters:	res_info -- (IN) Column info pointer by cci_get_result_info() index -- (IN) Column index
Returns:	Class name (char *)

CCI_GET_RESULT_INFO_IS_NON_NULL¶

#define CCI_GET_RESULT_INFO_IS_NON_NULL(T_CCI_COL_INFO* res_info, int index)¶

The CCI_GET_RESULT_INFO_IS_NON_NULL macro gets a value indicating whether the index-th column of a prepared SELECT list is nullable. It does not check whether the specified argument, res_info, is NULL and whether index is valid.

When a column of a SELECT list is not a column but an expression, CUBRID cannot judge it's NON_NULL or not; therefore, CCI_GET_RESULT_INFO_IS_NON_NULL macro always returns 0.

Parameters:	res_info -- (IN) Column info pointer by cci_get_result_info() index -- (IN) Column index
Returns:	0: nullable, 1: non NULL

CCI_GET_RESULT_INFO_NAME¶

#define CCI_GET_RESULT_INFO_NAME(T_CCI_COL_INFO* res_info, int index)¶

The CCI_GET_RESULT_INFO_NAME macro gets the index-th column's name of a prepared SELECT list. It does not check whether the specified argument, res_info, is NULL and whether index is valid. You cannot delete the returned memory pointer with free ().

Parameters:	res_info -- (IN) Column info pointer to cci_get_result_info() index -- (IN) Column index
Returns:	Column name (char *)

CCI_GET_RESULT_INFO_PRECISION¶

#define CCI_GET_RESULT_INFO_PRECISION(T_CCI_COL_INFO* res_info, int index)¶

The CCI_GET_RESULT_INFO_PRECISION macro gets the index-th column's precision of a prepared SELECT list. It does not check whether the specified argument, res_info, is NULL and whether index is valid.

Parameters:	res_info -- (IN) Column info pointer by cci_get_result_info() index -- (IN) Column index
Returns:	precision (int)

CCI_GET_RESULT_INFO_SCALE¶

#define CCI_GET_RESULT_INFO_SCALE(T_CCI_COL_INFO* res_info, int index)¶

The CCI_GET_RESULT_INFO_SCALE macro gets the index-th column's scale of a prepared SELECT list. It does not check whether the specified argument, res_info, is NULL and whether index is valid.

Parameters:	res_info -- (IN) Column info pointer by cci_get_result_info() index -- (IN) Column index
Returns:	scale (int)

CCI_GET_RESULT_INFO_TYPE¶

#define CCI_GET_RESULT_INFO_TYPE(T_CCI_COL_INFO* res_info, int index)¶

The CCI_GET_RESULT_INFO_TYPE macro gets the index-th column's type of a prepared SELECT list. It does not check whether the specified argument, res_info, is NULL and whether index is valid.

If you want to check which column is a SET type or not, use CCI_IS_SET_TYPE.

Parameters:	res_info -- (IN) pointer to the column information fetched by cci_get_result_info() index -- (IN) Column index
Returns:	Column type (T_CCI_U_TYPE)

CCI_IS_SET_TYPE¶

#define CCI_IS_SET_TYPE(u_type)¶

The CCI_IS_SET_TYPE macro check whether u_type is set type.

Parameters:	u_type -- (IN)
Returns:	1 : set, 0 : not set

CCI_IS_MULTISET_TYPE¶

#define CCI_IS_MULTISET_TYPE(u_type)¶

The CCI_IS_SET_TYPE macro check whether u_type is multiset type.

Parameters:	u_type -- (IN)
Returns:	1 : multiset, 0 : not multiset

CCI_IS_SEQUENCE_TYPE¶

#define CCI_IS_SEQUENCE_TYPE(u_type)¶

The CCI_IS_SET_TYPE macro check whether u_type is sequence type.

Parameters:	u_type -- (IN)
Returns:	1 : sequence, 0 : not sequence

CCI_IS_COLLECTION_TYPE¶

#define CCI_IS_COLLECTION_TYPE(u_type)¶

The CCI_IS_SET_TYPE macro check whether u_type is collection (set, multiset, sequence) type.

Parameters:	u_type -- (IN)
Returns:	1 : collection (set, multiset, sequence), 0 : not collection

cci_get_version¶

int cci_get_version(int *major, int *minor, int *patch)¶

The cci_get_version function gets the version of CCI library. In case of version "9.2.0.0001", 9 is the major version, 2 is the minor version, and 0 is the patch version.

Parameters:	major -- (OUT) major version minor -- (OUT) minor version patch -- (OUT) patch version
Returns:	Zero without exception (success)

Note

In CUBRID for Linux, you can check the file version of CCI library by using the strings command.

$ strings /home/usr1/CUBRID/lib/libcascci.so | grep VERSION
VERSION=9.2.0.0001

cci_init¶

void cci_init()¶

If you compile the CCI application program for Windows with static linking library(.lib), this function should be called always. In the other cases, this does not need to be called.

cci_is_holdable¶

int cci_is_holdable(int req_handle)¶

The cci_is_holdable function returns whether the request handle(req_handle) is holdable or not.

Parameters:	req_handle -- (IN) Request handle for the prepared statement
Returns:	1: holdable 0: not holdable CCI_ER_REQ_HANDLE

See also

cci_prepare()

cci_is_updatable¶

int cci_is_updatable(int req_handle)¶

The cci_is_updatable function checks the SQL statement executing cci_prepare() can make updatable result set (which means CCI_PREPARE_UPDATABLE is configured in flag when executing cci_prepare()).

Parameters:	req_handle -- (IN) Request handle for the prepared statement
Returns:	1 : updatable 0 : not updatable CCI_ER_REQ_HANDLE

cci_next_result¶

int cci_next_result(int req_handle, T_CCI_ERROR *err_buf)¶

The cci_next_result function gets results of next query if CCI_EXEC_QUERY_ALL flag is set upon cci_execute(). The information about the query fetched by next_result can be obtained with cci_get_result_info(). If next_result is executed successfully, the database is updated with the information of the current query.

You can execute multiple queries in the written order when CCI_EXEC_QUERY_ALL flag is set on cci_execute(). At this time, CUBRID brings the first query's result after calling cci_execute(); CUBRID brings the second and the other queries' results after calling cci_next_result function. At this time, the column information about the query result can be brought by calling cci_get_result_info() function whenever cci_execute() function or cci_next_result function is called.

In other words, when you run Q1, Q2, and Q3 at once with calling cci_prepare() function, the result of Q1 is brought by calling cci_execute(); the result of Q2 or Q3 is brought by calling cci_next_result. The result of Q1, Q2 or Q3 is brought by calling cci_get_result_info() function for each time.

sql = "SELECT * FROM athlete; SELECT * FROM nation; SELECT * FROM game";
req = cci_prepare (con, sql, 0, &error);
...
ret = cci_execute (req, CCI_EXEC_QUERY_ALL, 0, &error);
res_col_info = cci_get_result_info (req, &cmd_type, &col_count);
...
ret = cci_next_result (req, &error);
res_col_info = cci_get_result_info (req, &cmd_type, &col_count);
...
ret = cci_next_result (req, &error);
res_col_info = cci_get_result_info (req, &cmd_type, &col_count);

Parameters:	req_handle -- (IN) Request handle of a prepared statement err_buf -- (OUT) Database error buffer
Returns:	SELECT : The number of results INSERT, UPDATE : The number of records reflected Others : 0 Failure : Error code CCI_ER_REQ_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION

The error code CAS_ER_NO_MORE_RESULT_SET means that no more result set exists.

cci_oid¶

int cci_oid(int conn_handle, T_CCI_OID_CMD cmd, char *oid_str, T_CCI_ERROR *err_buf)¶

By the value of cmd argument, it executes the following behavior.

• CCI_OID_DROP: Deletes the given oid.
• CCI_OID_IS_INSTANCE: Checks whether the given oid is an instance oid.
• CCI_OID_LOCK_READ: Sets read lock on the given oid.
• CCI_OID_LOCK_WRITE: Sets write lock on the given oid.

Parameters:	conn_handle -- (IN) Connection handle cmd -- (IN) CCI_OID_DROP, CCI_OID_IS_INSTANCE, CCI_OID_LOCK_READ, CCI_OID_LOCK_WRITE oid_str -- (IN) oid err_buf -- (OUT) Database error buffer
Returns:	when cmd is CCI_OID_IS_INSTANCE 0 : Non-instance 1 : Instance < 0 : error when cmd is CCI_OID_DROP, CCI_OID_LOCK_READ or CCI_OID_LOCK_WRITE Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OID_CMD CCI_ER_OBJECT CCI_ER_DBMS

cci_oid_get¶

int cci_oid_get(int conn_handle, char *oid_str, char **attr_name, T_CCI_ERROR *err_buf)¶

The cci_oid_get function gets the attribute values of the given oid. attr_name is an array of the attributes, and it must end with NULL. If attr_name is NULL, the information of all attributes is fetched. The request handle has the same form as when the SQL statement "SELECT attr_name FROM oid_class WHERE oid_class = oid" is executed.

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid attr_name -- (IN) A list of attributes err_buf -- (OUT) Database error buffer
Returns:	Success: Request handle, Failure: Error code CCI_ER_CON_HANDLE CCI_ER_NO_MORE_MEMORY CCI_ER_CONNECT

cci_oid_get_class_name¶

int cci_oid_get_class_name(int conn_handle, char *oid_str, char *out_buf, int out_buf_len, T_CCI_ERROR *err_buf)¶

The cci_oid_get_class_name function gets the class name of the given oid.

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid out_buf -- (OUT) Out buffer out_buf_len -- (IN) out_buf length err_buf -- (OUT) Database error buffer
Returns:	Error code CCI_ER_CON_HANDLE CCI_ER_CONNECT CCI_ER_OBJECT CCI_ER_DBMS

cci_oid_put¶

int cci_oid_put(int conn_handle, char *oid_str, char **attr_name, char **new_val_str, T_CCI_ERROR *err_buf)¶

The cci_oid_put function configures the attr_name attribute values of the given oid to new_val_str. The last value of attr_name must be NULL. Any value of any type must be represented as a string. The value represented as a string is applied to the database after being converted depending on the attribute type on the server. To insert a NULL value, configure the value of new_val_str [i] to NULL.

Parameters:	conn_handle -- (IN) Connection handle oid_str -- (IN) oid attr_name -- (IN) The list of attribute names new_val_str -- (IN) The list of new values err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_CONNECT

cci_oid_put2¶

int cci_oid_put2(int conn_handle, char *oidstr, char **attr_name, void **new_val, int *a_type, T_CCI_ERROR *err_buf)¶

The cci_oid_put2 function sets the attr_name attribute values of the given oid to new_val. The last value of attr_name must be NULL. To insert a NULL value, set the value of new_val [i] to NULL.

Parameters:	conn_handle -- (IN) Connection handle oidstr -- (IN) oid attr_name -- (IN) A list of attribute names new_val -- (IN) A new value array a_type -- (IN) new_val type array err_buf -- (OUT) Database error buffer
Returns:	Error code (0: success) CCI_ER_CON_HANDLE CCI_ER_CONNECT

The type of new_val [i] for a_type is shown in the table below.

Type of new_val[i] for a_type

Type	value type
CCI_A_TYPE_STR	char **
CCI_A_TYPE_INT	int *
CCI_A_TYPE_FLOAT	float *
CCI_A_TYPE_DOUBLE	double *
CCI_A_TYPE_BIT	T_CCI_BIT *
CCI_A_TYPE_SET	T_CCI_SET *
CCI_A_TYPE_DATE	T_CCI_DATE *
CCI_A_TYPE_BIGINT	int64_t * (For Windows: __int64 *)

char *attr_name[array_size]
void *attr_val[array_size]
int a_type[array_size]
int int_val

...

attr_name[0] = "attr_name0"
attr_val[0] = &int_val
a_type[0] = CCI_A_TYPE_INT
attr_name[1] = "attr_name1"
attr_val[1] = "attr_val1"
a_type[1] = CCI_A_TYPE_STR

...
attr_name[num_attr] = NULL

res = cci_put2(con_h, oid_str, attr_name, attr_val, a_type, &error)

cci_prepare¶

int cci_prepare(int conn_handle, char *sql_stmt, char flag, T_CCI_ERROR *err_buf)¶

The cci_prepare() function prepares SQL execution by acquiring request handle for SQL statements. If a SQL statement consists of multiple queries, the preparation is performed only for the first query. With the parameter of this function, an address to T_CCI_ERROR where connection handle, SQL statement, flag, and error information are stored.

Parameters:	conn_handle -- (IN) Connection handle sql_stmt -- (IN) SQL statement flag -- (IN) prepare flag (CCI_PREPARE_UPDATABLE, CCI_PREPARE_INCLUDE_OID, CCI_PREPARE_CALL or CCI_PREPARE_HOLDABLE) err_buf -- (OUT) Database error buffer
Returns:	Success: Request handle ID (int), Failure: Error code CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_STR_PARAM CCI_ER_NO_MORE_MEMORY CCI_ER_CONNECT CCI_ER_QUERY_TIMEOUT CCI_ER_LOGIN_TIMEOUT

CCI_PREPARE_UPDATABLE, CCI_PREPARE_INCLUDE_OID, CCI_PREPARE_CALL or CCI_PREPARE_HOLDABLE can be configured in flag. If CCI_PREPARE_UPDATABLE is configured, updatable resultset is created and CCI_PREPARE_INCLUDE_OID is automatically configured. CCI_PREPARE_UPDATABLE and CCI_PREPARE_HOLDABLE cannot be used simultaneously in flag. If you want to call the Java Stored Procedure, specify CCI_PREPARE_CALL flag into the cci_prepare function. You can see an related example on cci_register_out_param().

The default value of whether to keep result set after commit is cursor holdability. Thus, if you want to configure CCI_PREPARE_UPDATABLE in flag of cci_prepare(), you should call cci_set_holdability() first before calling cci_prepare() so that cursor cannot be maintained.

However, not all updatable resultsets are created even though CCI_PREPARE_UPDATABLE is configured. So you need to check if the results are updatable by using cci_is_updatable() after preparation. You can use cci_oid_put() or cci_oid_put2() to update result sets.

The conditions of updatable queries are as follows:

• Must be SELECT.
• OID can be included in the query result.
• The column to be updated must be the one that belongs to the table specified in the FROM clause.

If CCI_PREPARE_HOLDABLE is set, a cursor is held as long as result set is closed or connection is disconnected after the statement is committed(see Cursor Holdability).

cci_prepare_and_execute¶

int cci_prepare_and_execute(int conn_handle, char *sql_stmt, int max_col_size, int *exec_retval, T_CCI_ERROR *err_buf)¶

The cci_prepare_and_execute function executes the SQL statement immediately and returns a request handle for the SQL statement. A request handle, SQL statement, the maximum length of a column to be fetched, error code, and the address of a T_CCI_ERROR construct variable in which error information being stored are specified as arguments. max_col_size is a value to configure the maximum length of a column to be sent to a client when the column of a SQL statement is CHAR, VARCHAR, BIT, or VARBIT. If this value is 0, full length is fetched.

Parameters:	conn_handle -- (IN) Connection handle sql_stmt -- (IN) SQL statement max_col_size -- (IN) The maximum length of a column to be fetched when it is a string data type in bytes. If this value is 0, full length is fetched. exec_retval -- (OUT) Success: Affected rows, Failure: Error code err_buf -- (OUT) Database error buffer
Returns:	Success: Request handle ID (int), Failure: Error code CCI_ER_CON_HANDLE CCI_ER_DBMS CCI_ER_COMMUNICATION CCI_ER_STR_PARAM CCI_ER_NO_MORE_MEMORY CCI_ER_CONNECT CCI_ER_QUERY_TIMEOUT

cci_property_create¶

T_CCI_PROPERTIES * cci_property_create()¶

The cci_property_create function creates T_CCI_PROPERTIES struct to configure DATASOURCE of CCI.

Returns:	Success: T_CCI_PROPERTIES struct pointer in which memory is allocated, Failure: NULL

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_destroy(), cci_datasource_release()

cci_property_destroy¶

void cci_property_destroy(T_CCI_PROPERTIES * properties)¶

The cci_property_destroy function destroys T_CCI_PROPERTIES struct.

Parameters:	properties -- T_CCI_PROPERTIES struct pointer to be destroyed

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_destroy(), cci_datasource_release()

cci_property_get¶

char *cci_property_get(T_CCI_PROPERTIES * properties, char *key)¶

The cci_property_get function retrieves the property value configured in the T_CCI_PROPERTIES struct.

Parameters:	properties -- T_CCI_PROPERTIES struct pointer which gets value corresponding to key key -- Name of property to be retrieved (For name and description available properties, see the cci_property_set())
Returns:	Success: String pointer of value corresponding to key, Failure: NULL

See also

cci_property_create(), cci_property_destroy(), cci_property_get(), cci_property_set(), cci_datasource_create(), cci_datasource_destroy(), cci_datasource_release()

cci_property_set¶